Capture funnel finished + meaning-preserving archival + AI composer (Epics 13/16/15) - #2

Close Epic 13's capture funnel with a desktop review lane: a pure, token-authed
API client + an MV3 popup that surfaces each recent Inbox capture with its AI
suggested-board chip (one-tap confirm), degrading to a manual picker.

- extension/api-client.js: pure ESM (no DOM/chrome.*) — save/listRecent/
  getSuggestion/listBoards/assign + reviewAction, speaking ONLY the Epic 12+14
  /api/v1/* contracts. No server-side files; no second backend.
- popup.html/js: the review lane (chip→assign on confirm, manual picker fallback
  that also covers a failed suggestion call so an item is always promotable).
- options + manifest: instance URL + token in chrome.storage.local (Bearer-only,
  never logged/URL'd; remote instance must be https — no cleartext token leak).

Tests (7) are two-layered: fake-fetch contracts pin URL/Bearer/body, and an
inject-backed round-trip routes the client's fetch into a real buildServer to
prove save→Inbox and assign→board_id-moves against the LIVE contract (it caught
the real assign response shape). newest-first is honest passthrough (server-
ordered). No-regression: diff is extension/* + the test-script line only; assign
moves only on explicit confirm.

Party-mode review applied: https-only remote, always-promotable fallback,
getSuggestion/listBoards coverage. Suite 438 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a kind='snapshot' self-contained-HTML asset so a curated link's content
survives the page going down. Captured through the EXISTING single-Chrome
sidecar (no second Chromium), persisted ADDITIVELY (never wipes the screenshot).

- config: derived snapshotsDir under DATA_DIR + ensureDataDir mkdir.
- db/snapshot-asset.ts: writeSnapshotAssetDirect — additive single-row upsert on
  a stable ${id}-snapshot id (NOT writeItemDirect's replace-all), dedupe-read +
  upsert in one transaction; enqueued wrapper for standalone callers.
- capture/url-snapshot.ts: createUrlSnapshotCapture (byte cap + teardown) +
  runSnapshotJob — status-neutral (enqueueJob, never runItemJob, so a failed
  archive never flips a curated item to error); timeout SIGKILLs Chrome before
  the slot releases. Default SingleFile driver is dynamic-imported (AGPL isolated)
  and drives the existing browser via CDP — no 2nd Chrome.

single-file-cli@2.0.83 scored (supply_chain .81 / quality .99 / vuln 1.0 /
maint .93; AGPL) and added as an optionalDependency + lazy import.

Party-mode review caught a nested-enqueue deadlock on the success path (job
holding the writer slot re-entered enqueueTransaction) — fixed with the in-slot
direct write + a success-path regression test. No-regression test proves the
screenshot row AND file survive (two asset rows); dedupe asserts the skipped
write, not just one row. Suite 448 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Make archival opt-in and tied to promotion, so a small box archives what was
curated — not every bucket link.

- descriptor: additive OPTIONAL archive_on_promote flag (default-off) +
  archivesOnPromote() reader; pre-wave descriptors validate + read off (no
  migration — the descriptor is a JSON blob).
- assign verb (the ONE path): after the moves + earned enrichment, if the TARGET
  board archives-on-promote, enqueue a 16.1 snapshot for each MOVED item
  (forward-only; never skipped/failed; fire-and-forget; graceful). The composer
  (15.2) inherits this with no second code path.
- per-item REST action POST /api/v1/items/:id/archive (not a skill): 404 unknown,
  422 no-source, 202 queued.
- enqueueSnapshot injectable threaded buildServer → v1 → assignItems so tests
  spy it and never launch Chrome.

The earned takeaway (item.fields) coexists with the snapshot asset — disjoint
state, proven across the real spy-LLM enrich+trigger seam. Default-off, batch,
and 422 paths covered. Suite 459 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Surface snapshot disk usage and let operators backfill existing curated items —
so "no storage limit" never becomes a silent surprise. Closes Epic 16.

- db/archive-footprint.ts: read-only archiveFootprint — total bytes over
  kind='snapshot' files only (stat-on-disk, missing→0, never throws); surfaced
  at GET /api/archive/footprint. Mutates nothing.
- db/archive-backfill.ts: backfillSnapshots — enqueues a snapshot for each
  eligible (archive-on-promote board) item lacking one, serially on the single
  concurrency-1 worker. Idempotent by item id (skips already-snapshotted), so
  re-runs/resume create no duplicates.
- db/archive-backfill-cli.ts: `npm run archive:backfill` operator runner (awaits
  the serial drain before closing; warns to stop the server first — the
  concurrency-1 guarantee is per-process).

Additive/read-only (NFR-BC); no-parallel-Chromium inherited from enqueueJob
(in-process). Party-mode review applied (non-vacuous no-regression + byte-level
exclusion tests; cross-process server-stop warning). Suite 465 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add the additive `view` table — a composed board is a read-only LENS over canonical
items (filter + optional pin/order overlay stored in the view row), never a
duplicate pile. Confirmed with the maintainer first (workshop hinge #1: lens, not
join / not m2m).

- db/schema.ts + db/index.ts: additive `view` table {id, name, filter JSON,
  optional order, optional captions} in drizzle + raw BOOTSTRAP_SQL lockstep.
  "view"/"order" are SQL keywords → quoted in the raw DDL. item/board schemas
  byte-for-byte unchanged (no item→view FK, no join table). D12 held.
- db/view.ts: resolveView — two-path (FTS MATCH across boards when a text query is
  present; plain SELECT + structured predicates otherwise, so a no-query lens never
  dead-matches). Order overlay pins matching ids first. SELECT-only — edits at an
  item's home flow into every view (canonical meaning). All predicate values bound.
- db/search.ts: export toFtsPhrase (shared, no duplicate).

NFR-BC: additive table, fresh-DB boot verified, zero item-row migration. Tests are
discriminating (dynamic N→N+1; overlay pins a non-first id; read-only asserts row
byte-identity; two-descriptor cross-board render). Party-mode review applied.
Epic 15 Story 1 of 3. Suite 475 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The composer: describe (or let the AI infer) a board and it PROPOSES how to build
it from saved items — home-board assignments and/or a cross-board view — as a
reviewable proposal that persists NOTHING until accept.

- skills/compose-collection.ts: composeCollectionSkill (propose-only) +
  acceptComposerProposal (thin dispatcher). Accept reuses the ONE assign verb
  (14.2 assignItems) for assignments and the 15.1 createView for a view — no
  second move/enrichment path (D8). Both the description AND scraped item content
  are fenced as untrusted in the prompt.
- descriptor/guardrails.ts: extract a generic boundedRepair<T,V,E> (≤1 repair);
  validateAndRepair becomes a thin behavior-preserving wrapper. The composer
  reuses the same discipline with its own board-aware validator + ComposerError.
- db/view.ts: createView write primitive (additive, serialized).

Degrades to an editable draft with no AI (never a 500). Accept is atomic on board
validity (fail-fast before any move) and reversible. NFR-BC: a bystander item
keeps its home board. Party-mode review applied (typed-error union fix, atomic
accept, item-dedup, fencing/bystander tests). Source typechecks clean under
strict. Epic 15 Story 2 of 3. Suite 485 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The deliberate escape hatch (D11): turn a read-only lens (15.1) into a real,
hand-prunable board by COPYING its currently-resolved items — never a move.

- db/materialize.ts: materializeView — resolveView → insertBoard → writeItem a
  NEW item row per item (new id, dest board, fields/notes/favorite by value).
  Asset rows reuse the source file by path+hash (ZERO file I/O — referenced, not
  rewritten; NFR-1). Source items/asset rows byte-for-byte unchanged.
- db/item-actions.ts: deleteItemWithAssets is now reference-aware — it won't
  unlink a file another asset row still resolves to (basename-keyed, matching the
  unlink key). Makes the shared materialized/source file safe to delete around.

Copies are independent (divergence owned by the copy). Destination descriptor is
minimal (fields:[]) — a documented v1 choice (notes/favorite editable, fields not;
no cross-source descriptor merge). Additive/NFR-BC (asserted +1 board/+N items/+N
assets, nothing else mutated). Party-mode review applied (guard-key alignment,
source-asset + additive assertions, edge tests). Source typechecks clean.
Epic 15 complete. Suite 492 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…hots)

Epic 16 added snapshot assets under snapshots/<id>.html but deleteItemWithAssets
still resolved every asset as basename-under-screenshotsDir, so deleting an item
or board orphaned its archived .html. Route each asset to its own dir by the
stored path prefix (snapshots/ → the snapshots sibling of screenshotsDir), and
re-key the shared-file guard on the full relative path so guard and unlink agree
(a same-basename file in another dir is no longer a false share). No signature
change. Tests: snapshot .html is unlinked; cross-dir same-basename files don't
cross-delete. Suite 494 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The single-Chrome / concurrency-1 guarantee is per-process, so running the
archive:backfill CLI alongside the live server put two Chromiums on the box
(the OOM NFR-1 exists to prevent) — previously only a doc warning. Add a
cross-process guard: isServerListening() probes the configured host:port and
the CLI refuses to start if a server answers, with a BOARD_ALLOW_CONCURRENT_CHROME=1
override for operators who accept the risk. Suite 497 pass / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>